Page last updated: May 16, 2022
ethstake.exchange style guide
Content on ethstake.exchange is crowdsourced and primarily written by our incredible contributors. This style guide aims to standardize certain aspects of writing content to make the contribution process smoother.
You should read this style guide before you contribute to ethstake.exchange.
Who can submit content to ethstake.exchange
Anyone! ethstake.exchange is entirely open source, and many of its best pages are submitted by curious learners who expanded their notes into documentation pages now living on the site.
Audience
ethstake.exchange content caters to a large and varied audience. Because ethstake.exchange caters to a wide spectrum of users, all content on the site should make an effort to explain any technologies and concepts as simply as possible.
Loosely we can categorize the site audiences as:
Individuals
App users, investors, enthusiasts, or anyone who is "new to Ethereum".
Example user journeys:
- "I want to learn more about Ethereum, to know if I think it’s credible or not. Once I’ve answered a few basic questions, I want to try using Ethereum"
- "I know I need an Ethereum wallet, and want a good recommendation"
- "I want to learn how to run an Ethereum node"
- "I want to get a sense of the size and activity of the Ethereum community, to decide if it's active enough, so I can get help if needed"
- "I’m excited about Ethereum and want to get involved, but I don’t know what to do next"
Developers
Developers or others who want technical information about Ethereum.
Example user journeys:
- "I'm a developer but I have no background in crypto and want to understand the Ethereum tech stack at a high level"
- "I want to get a sample Ethereum project up and running fast, to get a sense of how difficult or easy it is to build a real project on Ethereum"
- "I want to learn about Ethereum's technical roadmap"
- "I’ve started work on an Ethereum project, and want to try out a few smart contract testing libraries"
Enterprises
People, businesses, and other organizations who want to understand Ethereum's value in an enterprise setting.
Example user journeys:
- "I want to understand what use cases Ethereum can help with, and how it compares to other chains or other technologies"
- "I work at a business that is beginning an Ethereum related project, and want to learn more"
- "I want to understand the differences between private Ethereum chains, consortium chains, and the public Ethereum Mainnet"
- "I want to know the current status of Ethereum - how long has it been in production, how much usage it has, what's the direction of new development - to decide if I am confident to build my project on top of it"
Objectivity
ethstake.exchange documentation (and content at large) aims to maintain a credibly neutral source of truth to inform readers about Ethereum and its ecosystem. Some examples of things that we don't want in the content on ethstake.exchange:
Grand, unverifiable claims about Ethereum or adjacent technologies
e.g. "Ethereum will take over the world because..."
Hostile or confrontational language aimed at any organization or person
e.g. "Company X is bad because they are centralized!"
Politically charged rhetoric
e.g. "This political party is better for decentralization because..."
Tone
The tone of the content on the site should be welcoming, friendly and straightforward. Jargon should be minimized and simple language used instead.
Read the ethstake.exchange design principles for more on direction tone.
Best practices
Use American English
For words that have multiple spellings, use American English over British English.
For example:
- "decentralized" over "decentralised"
- "color" over "colour"
- "analyze" over "analyse"
Acronyms
When introducing an unfamiliar acronym, spell out the full term, and put the acronym in parentheses. Put both the full term and acronym in bold.
For example:
"Ethereum, like Bitcoin, currently uses a consensus protocol called proof-of-work (PoW)."
Consistency
Many of the topics covered on ethstake.exchange are technically complex. To reduce confusion to the reader, terms should be used consistently. For example, don't cycle back-and-forth between proof-of-work and PoW at random.
Ethereum
Ethereum is a proper noun and should always be capitalized.
- "Ethereum" not "ethereum"
Ether
Ether is a common noun and should not be capitalized unless at the beginning of a sentence. ETH, on the other hand, is a currency abbreviation (and ticker symbol) and should always be capitalized.
- "ether" not "Ether"
- "ETH" not "eth or Eth"
Mainnet
When referring to the Ethereum Mainnet (i.e. not referring to a testnet) use the proper noun. Proper nouns help avoid confusion and build greater understanding.
Correct usage:
- Mainnet
- Ethereum Mainnet
Incorrect usage:
- main net
- mainnet
- Main net
- Ethereum mainnet
Proof-of-work / Proof-of-stake
Proof-of-work should be capitalized at the beginning of a sentence. In any other instance, all letters should be lower case. In either case, proof-of-work should be hyphenated between each word.
Correct usage:
- Proof-of-work
- proof-of-work
Incorrect usage:
- Proof-of-Work
- Proof of work
- proof of work
The same rules we apply to proof-of-work are applicable to proof-of-stake, proof-of-authority, proof-of-humanity, proof-of-individuality, etc.
Use active voice
Sentences using active voice are more concise and efficient, making your writing more engaging and easier to comprehend.
Active voice sentence: an actor acts on a target
"The man bought a car."
Passive voice sentence: a target acts on an actor
"The car was bought by a man."
This isn't an easy one, especially for non-native English speakers. If you aren't sure, don't worry. We'll help with any of these.
Linking to internal pages
When linking to another page on
ethstake.exchange, use the relative path over the absolute path. Do not hard-code the language path
(i.e. /en/) in any links. This maintains consistent functionality across different
language versions of the site.
<!-- Good -->
Read more about [smart contracts](/docs/developers/smart-contracts/)
<!-- Bad -->
Read more about [smart contracts](/en/docs/developers/smart-contracts)
Read more about [smart contracts](https://ethstake.exchange/en/docs/developers/smart-contracts)
Please also add a trailing slash to all links. This keeps links consistent and avoids redirects, which hurts site performance.
<!-- Good -->
Read more about [smart contracts](/docs/developers/smart-contracts/)
<!-- Bad -->
Read more about [smart contracts](/docs/developers/smart-contracts)
Linking to images
When adding an image to a page, the image should be downloaded and placed in the same folder as the markdown file. You can reference the image like this:
<!-- Good -->
<!-- Bad -->
This helps us ensure the image will be available.
Using emojis
Everyone loves emojis 🥰 To standardize
the appearance of all Emojis across browsers, ethstake.exchange uses an <Emoji />
React component.
<--- Good --->
The London Upgrade is live <Emoji text=":heart:" size={1} />
The London Upgrade is live <Emoji text="❤️" size={1} />
<--- Bad --->
The London Upgrade is live ❤️
Header casing
This site uses sentence casing for header names as a convention. Only the first word and proper nouns are capitalized. This applies to all markdown files on lines that begin with hashes (#).
<!-- Good -->
## Minting your NFT
### Setting up your wallet
### Get enough ether
<!-- Bad -->
## Minting Your NFT
### Setting Up Your Wallet
### Getting Enough Ether
Article authors
When citing articles from a specific author or organization, use the article's name as a link, followed by a dash, then the author's name italicized.
<--- Good --->
- [A rollup-centric ethereum roadmap](https://ethereum-magicians.org/t/a-rollup-centric-ethereum-roadmap/4698) — _Vitalik Buterin_
- [Oracles](https://docs.ethhub.io/built-on-ethereum/oracles/what-are-oracles/) – _EthHub_
<--- Bad--->
- [A rollup-centric ethereum roadmap by Vitalik Buterin](https://ethereum-magicians.org/t/a-rollup-centric-ethereum-roadmap/4698)
- [EthHub on Oracles](https://docs.ethhub.io/built-on-ethereum/oracles/what-are-oracles/) – _EthHub_
Anything else?
Like all content on ethstake.exchange, this style guide is an open-source work-in-progress with room for improvement. If there is anything you think should be added to improve this document please suggest an edit on GitHub.